doc/design-doc/2.8.strfmt-formated string output with variable filling.txt

   1 doc of shlib
   2
   3   Copyright (C) 2022- Free Software Foundation, Inc.
   4
   5   Copying and distribution of this file, with or without modification,
   6   are permitted in any medium without royalty provided the copyright
   7   notice and this notice are preserved.
   8
   9 The following contributions warranted legal paper exchanges with the
  10 Free Software Foundation.
  11
  12
  13
  14 # introduction
  15 ==============
  16
  17     this charpter is a design-doc for strfmt.shlib.
  18     strfmt.shlib is used for variable filled text output, and recognize the
  19 element in a formated string, save it to the specified variable.
  20     strfmt.shlib is used for:
  21 @ general variable filled text string output.
  22 @ define string formate in var[1], and output in var(same as var[0]). this
  23   feature is used for system paramter define, such as global path define. due
  24   to some part of string will be setted in run-time, a formated string is
  25   suitable for this, and the format defined in variable var_fmt or var[1], it
  26   is easy to use it directly by the name of 'var'. for example: run time info
  27   path in /var/<something>/<something> is used for a program. here, something
  28   can be a dynatmical string such as pid, or program name. it defined by a
  29   string format, using it by invoking of 'strfmt @var'.
  30 @ templete file. some string should be replaced in runtime, some content or
  31   element will be generated dynamically.
  32 @ formated file name text generating, and reverse recognize element in
  33   variable. this generate/recognize operation is also used for line string
  34   processing in text file.
  35 @
  36
  37
  38 # features
  39     it implemented those features:
  40 @ evaln, an alias cmd for eval a string until $var is fully expanssioned.
  41 @ strfmt(), output formated string with variable content filling by formated
  42   string.
  43 @ strfmt(), string format variable defined with _fmt/_FMT surffix, and output
  44   to the variable without surffix. or defined in var[1], outputed in var.
  45 @ paramter for a string. it can be used as '${var param1 param2}', it can set
  46   variable dynamically when the formated string is generating.
  47 @ strdispatch(), by using the same formated string for strfmt(), it recognize
  48   text content in a string, and store it into the variable in formated string.
  49 @
  50
  51
  52 # API
  53
  54 * evaln,
  55 * strfmt(),
  56 * str2var(),
  57 * strfmtset(), set for eval, evaln, '\' prefix specal char transfer.
  58
  59 # example
  60
  61     see example in testing code.
  62
  63 ```
  64 .shlibinc
  65 include stdio.shlib
  66 include strfmt.shlib
  67
  68 data1_fmt="string format: @{format_str1}"
  69 data_array[1]="output string"
  70
  71 attr_declare str_test='
  72     this is a text for strfmt() testing.
  73 @{SHEBANG}
  74 ############################################################
  75
  76 ############################################################
  77 ############################################################
  78 @{TESTING} for pure testing.
  79 # source: @{SRCFILE}
  80 # author: @{AUTHOR} (email:@{EMAIL})
  81 # date: @{DATE}@{TIME}
  82 ############################################################
  83 @{COPYING}
  84 ############################################################
  85 # note: @{NOTE}
  86 ############################################################
  87
  88 #####################
  89 # include file.
  90 #####################
  91 @(listgen include)
  92 '
  93
  94 testing ()
  95 {
  96         dbgout "= strfmt @data1_fmt =\n"
  97         strfmt @data1_fmt
  98         declare -p data1
  99         echo
 100
 101         dbgout "= strfmt @data_array =\n"
 102         strfmt @data_array
 103         declare -p data1
 104         echo
 105
 106         dbgout "= strfmt @str_test =\n"
 107         strfmt @str_test
 108 }
 109 ```